\documentclass[a4paper,10pt]{article}
\usepackage[utf8]{inputenc}
\usepackage{graphicx} 
\usepackage{listings}
\usepackage{mips}


%opening
\title{66.20 Organización de Computadoras \\ Trabajo Práctico 1: Código MIPS}
\author{(82341) Monzón, Maximiliano - maximilianohm@gmail.com\\
(88153) Toccalino, Elvio - etoccalino@fi.uba.ar\\
(86052) Ribotta, Mariano - fpfiuba@gmail.com}
\date{Segundo Cuatrimestre, 2011}

\begin{document}

\maketitle

\renewcommand{\contentsname}{Índice}
\tableofcontents
\newpage

\section{Introducción}

En el presente trabajo práctico implementaremos una pila de \textit{doubles}. Una \textbf{pila} es un contenedor del tipo \textbf{LIFO} (\textit{last in, first out}) donde el último elemento en almacenarse es el primero en obtenerse a la hora de leer de la estructura. La particularidad de esta implementación es que escribimos el código que implementa la \textbf{pila} directamente en el lenguaje ensamblador del procesador que va a correr los programas que lo usen (\textbf{MIPS}).

Para asegurar que el código escrito sea compatible con el código escrito por quien pretende usar la \textbf{pila}, sea un programador humano o un programa compilador que genera código a partir de otro lenguaje, usamos como guía el ABI de la arquitectura {\textbf{MIPS}.

\section{La Pila}

\subsection{API}

%
% API
%
\lstset {breaklines=true, basicstyle=\footnotesize, columns=fullflexible, language=C }

\begin{lstlisting}
/* Push: Inserta un numero de punto flotante en la pila.
 * Precondicion: Se debe haber reservado memoria para la pila y se deben suministrar los parametros que la definen (topePila, tamanioPila y cantidadElementos).
 * Poscondicion: Almacena en la pila el valor contenido en el parametro valor, actualizando el valor de la variable referenciada por *cantidadElementos que contabiliza los elementos agregados a la pila.
 * Parametros:
 *   *topePila: direccion de memoria de la pila.
 *    tamanioPila: cantidad maxima de elementos que permite albergar la pila.
 *   *cantidadElementos: direccion de memoria de la variable que contabiliza la cantidad de elementos que posee la pila.
 *    valor: valor que se agrega a la pila.
 * Retorno: Retorna el valor 1 en caso de haber llevado a cabo con exito la operacion. Caso contrario, retorna 0. */
int Push (double *topePila, int tamanioPila, int *cantidadElementos, double valor);

/* Pop: Remueve el ultimo numero de punto flotante agregado a la pila y lo retorna en la variable referenciada por el parametro *valor.
 * Precondicion: Se debe haber reservado memoria para la pila y se deben suministrar los parametros que la definen (topePila, tamanioPila y cantidadElementos).
 * Poscondicion: Almacena en la variable referenciada por el parametro *valor, el ultimo elemento agregado a la pila. Remueve dicho valor y actualiza el valor de la cantidad de elementos que alberga la pila.
 * Parametros:
 *   *topePila: direccion de memoria de la pila.
 *    tamanioPila: cantidad de elementos que permite albergar la pila.
 *   *cantidadElementos: direccion de memoria de la variable que contabiliza la cantidad de elementos que posee la pila.
 *    *valor: direccion de memoria de la variable donde se escribe el valor que se remueve de la pila.
 * Retorno: Retorna el valor 1 en caso de haber llevado a cabo con rxito la operación. Caso contrario, retorna 0. */
int Pop(double *topePila,int tamanioPila,int *cantidadElementos,double *valor);

/* SumarTodosLosElementos: Recorre secuencialmente los elementos que alberga la pila efectuando la suma de los mismos.
 * Precondicion: Se debe haber reservado memoria para la pila y se debe suministrar los parametros que la definen (topePila, tamanioPila y cantidadElementos).
 * Poscondicion: Almacena en la variable referenciada por el parámetro *resultadoSuma, la suma del valor actual, sumado a los numeros de punto flotante almacenados en la pila.
 * Parametros:
 *   *topePila: direccion de memoria de la pila.
 *    tamanioPila: cantidad de elementos que permite albergar la pila.
 *   *cantidadElementos: direccion de memoria de la variable que contabiliza la cantidad de elementos que posee la pila.
 *    resultadoSuma: direccion de memoria de la variable a la se le suman los numeros de punto flotante que contiene la pila.
 * Retorno: Retorna el valor 1 en caso de haber realizado la suma total de los elementos correctamente. Caso contrario, retorna 0. */
int SumarTodosLosElementos(double *topePila,int tamanioPila,int *cantidadElementos,double *resultadoSuma)
\end{lstlisting}
%
% fin de API
%


\subsection{Modelo conceptual de la pila}

La pila usada como modelo para el trabajo práctico consta de un comienzo, un final, y un índice que en todo momento indica cuál es el último valor ingresado. Este último valor ingresado se conoce como \textit{tope de pila}, y es el valor más relevante.
El siguiente esquema ilustra el concepto.

%
% esquema de pila.
%
\includegraphics[width=300px]{diagrama-pila.png}

Como se aprecia en el esquema, la pila guarda los valores ingresados en posiciones concecutivas. Los valores ingresados primero van hacia el fondo de la pila, y es el último valor ingresado el primero en salir.

\subsection{Dónde existe la pila}

La pila esquematizada en la sección anterior tiene una existencia real en la memoria de la computadora durante la ejecución del código.
En la segunda sección del apéndice se puede ver cómo el \textit{caller} declara la pila entre sus variables locales. Esto significa que la pila real, es decir, el bloque de memoria donde las funciones descritas guardan los datos de manera consecutiva, reside en el stack-frame de la función \textit{caller}, más específicamente, en la sección de variables locales.

\section{Compilación Del Programa}

\subsection{\textit{Flags} De Interés}
\begin{enumerate}
  \item -O0 : evita aplicar optimizaciones al código original.
\end{enumerate}

\subsection{Requerimientos De Compilación}
\begin{itemize}
  \item El sistema debe compilarse en un arquitectura MIPS32.
  \item El sistema debe contar con el compilador gcc.
  \item El sistema debe contar con la herramienta \textbf {make} para la compilación de acuerdo a las reglas definidas.
  \item El usuario debe contar con permisos de lecura/escritura en los directorios donde se encuentren ubicados los archivos fuentes del comando.
\end{itemize}

\subsection{Descripción De Las Reglas De \textit{Build}}
\begin{enumerate}
  \item Opción \textit {tp1} (Opción por defecto): Compila el programa y ubica el ejecutable en el directorio \textit{dist}.
  \item Opción \textit {tests}: Realiza lo mismo que la opción \textit{tp1}, pero agrega, en el directorio \textit{dist}, los cuatro ejecutables correspondientes a las pruebas.
  \item Opción \textit {clean}: Elimina los archivos generados por ejecuciones previas de \textbf{make}.
\end{enumerate}

\section{Pruebas}

El código escrito fue sujeto a múltiples pruebas, que se describen a continuación, con el objetivo de corroborar el comportamiento individual de las funciones, la interacción entre las mismas, y los estados de la pila durante operaciones.

\subsection{Prueba a cumplir}

El enunciado del trabajo práctico describe una prueba que debe ser tomada como ejemplo para demostrar el correcto funcionamiento del código. Su ejecución existosa, junto con la de otras pruebas, se puede ver en el \textbf{seguimiento de las pruebas}.

\subsection{Descripción De Las Pruebas}

Las pruebas se dividen en dos grupos: las pruebas unitarias, y las de integración.

\subsubsection{Pruebas unitarias}

Consta de una batería chica de pruebas para cada una de las tres funciones

\begin{itemize}
 \item test-pop.c: Comprueba que Pop se comporta como es esperado ante la pila vacía, y la pila vaciada.
 \item test-push.c: Comprueba que Push no rebalsa la pila.
 \item test-suma.c: Comprueba que SumarTodosLosElementos responde correctamente ante la pila vacía, llena y con distintas cargas.
\end{itemize}

\subsubsection{Pruebas de integración}

Las mismas consisten de dos programas que combinan llamados a las funciones escritas en distintas situaciones.

\begin{itemize}
 \item main.c: Prueba original del enunciado del trabajo práctico.
 \item test-full.c: Prueba similar a la del enunciado, pero con una pila de mayor tamaño, y más operaciones de push y pop.
\end{itemize}


\subsection{Seguimiento de las pruebas}

Se muestra ahora el resultado de correr el total de las pruebas, resultantes de ejecutar \textit{make tests}.

\noindent Prueba: ./test-pop\\
\textbf{Resultado esperado:}\\
\indent Prueba 1: OK\\
\indent Prueba 2: OK\\
\indent Prueba 3: OK\\

\noindent \textbf{Resultado de la prueba}: OK.  El resultado es el esperado.

\begin{center}
\rule{150px}{1px}
\end{center}

\noindent Prueba: ./test-push\\
\textbf{Resultado esperado:}\\
\indent Prueba 1: OK\\
\indent Prueba 2: OK\\

\noindent \textbf{Resultado de la prueba}: OK.  El resultado es el esperado.

\begin{center}
\rule{150px}{1px}
\end{center}

\noindent Prueba: ./test-suma\\
\textbf{Resultado esperado:}\\
\indent Prueba 1: OK\\
\indent Prueba 2: OK\\
\indent Prueba 3: OK\\
\indent Prueba 4: OK\\
\indent Prueba 5: OK\\
\indent Prueba 6: OK\\

\noindent \textbf{Resultado de la prueba}: OK.  El resultado es el esperado.

\begin{center}
\rule{150px}{1px}
\end{center}

\noindent Prueba: ./tp1\\
\textbf{Resultado esperado:}\\
\indent El resultado de la suma de los valores de la pila es: 10.0\\

\noindent \textbf{Resultado de la prueba}: OK.  El resultado es el esperado.\\

\begin{center}
\rule{150px}{1px}
\end{center}

\noindent Prueba: ./test-full\\
\textbf{Resultado esperado:}\\
\indent Prueba 1: OK\\

\noindent \textbf{Resultado de la prueba}: OK.  El resultado es el esperado.

\end{document}
